docs: fix stale file references in MDM templates - #905

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Files matching docs-mdm/mobileconfig:\n'
git ls-files | rg '(^|/)netbird-macos\.mobileconfig$|mdm-integration\.mdx$|docs-static/files|docs' || true

printf '\nmobileconfig relevant lines:\n'
sed -n '1,120p' public/docs-static/files/netbird-macos.mobileconfig 2>/dev/null || true

printf '\nmdm integration relevant lines:\n'
sed -n '200,255p' src/pages/client/mdm-integration.mdx 2>/dev/null || true

printf '\nSearch for Developer ID Installer signs/signing/profiles:\n'
rg -n "Developer ID Installer|Apple Configurator|Configuration Profiles|sign the profile|productsign|CMS|Profile Manager|MDM" public src -S || true

Repository: netbirdio/docs

Length of output: 50371

🌐 Web query:

Apple Developer ID Installer certificate configuration profiles Developer ID Signing identity

💡 Result:

Developer ID certificates are used to sign macOS software distributed outside the Mac App Store, allowing Gatekeeper to verify the developer's identity and ensure the software has not been tampered with [1][2]. There are two primary types of Developer ID signing identities, each with a specific purpose [3][4]. Developer ID Application Certificate This certificate is used to sign Mac applications, plug-ins, kernel extensions, system extensions, and disk images [5][6][4]. It is the standard identity for signing the executable code within your software [5]. Developer ID Installer Certificate This certificate is specifically used to sign Mac Installer Packages (.pkg files) [7][8][5]. You must use this certificate when packaging your app for distribution via an installer [7]. It is critical to use the correct certificate; while tools like productsign may technically allow you to sign an installer package with a Developer ID Application certificate, doing so will result in an installer that fails on the destination Mac [7]. Provisioning Profiles While code signing primarily relies on the certificate and private key, some macOS apps may utilize Developer ID provisioning profiles to access advanced capabilities, such as CloudKit and push notifications [8][1][2]. These profiles tie together the developer's certificates and authorized entitlements [9]. If your application requires these advanced features, you must ensure your Developer ID provisioning profile is valid for the installed version of your application to function correctly [8]. Best Practices - Creation: You can generate up to five of each certificate type via your Apple Developer account or Xcode [1][3]. - Notarization: Regardless of which Developer ID certificate you use, all software distributed outside the Mac App Store should be notarized by Apple to provide users with confidence that the software has been scanned for malicious content [2][6]. - Verification: Gatekeeper evaluates the validity of your Developer ID certificate at installation and/or launch [1]. If a Developer ID Installer certificate expires, the package must be re-signed with a valid certificate to remain installable [1]. However, apps already installed and signed with a valid Developer ID Application certificate generally continue to run [8]. - Security: Always maintain backups of your signing identities (the certificate and its private key) [3]. For command-line operations, use productsign or pkgutil to sign and verify your installer packages to ensure they include the required secure timestamps [5].

Citations:

• 1: https://developer.apple.com/help/account/certificates/create-developer-id-certificates/
• 2: https://developer.apple.com/developer-id/
• 3: https://developer.apple.com/forums/thread/732320
• 4: https://developer.apple.com/forums/thread/698732
• 5: https://developer.apple.com/documentation/security/resolving-common-notarization-issues
• 6: https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution
• 7: https://help.apple.com/xcode/mac/current/en.lproj/deve51ce7c3d.html
• 8: https://developer.apple.com/help/account/reference/certificate-types
• 9: https://developer.apple.com/documentation/technotes/tn3125-inside-code-signing-provisioning-profiles

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'netbird-macos.mobileconfig:\n'
cat -n public/docs-static/files/netbird-macos.mobileconfig | sed -n '1,80p'

printf '\nmdm integration lines 210-250:\n'
cat -n src/pages/client/mdm-integration.mdx | sed -n '210,250p'

printf '\nSearch for Apple Configurator/Developer ID Installer in docs/source:\n'
rg -n "Apple Configurator|Developer ID Installer|productsign|CMS signing|Configuration Profile|Configuration Profiles|unsigned profile|MDM.*sign|Profile Manager" public src -S

Repository: netbirdio/docs

Length of output: 11529

🌐 Web query:

Apple MDM configuration profile signing CMS Xsign MobileConfig Profile Manager

💡 Result:

Apple configuration profiles (.mobileconfig) can be signed to guarantee data integrity [1][2]. Signed profiles help prevent unauthorized tampering and, when signed with a trusted certificate, avoid the "Profile is not signed" warning displayed to users [3]. Technical Mechanism Configuration profiles are XML property lists [2][3]. Signing a profile involves wrapping the XML in a CMS (Cryptographic Message Syntax) Signed Data structure [1][4][5]. This is commonly referred to as "CMS signing" or "Xsign" in some contexts [1][6]. The resulting file is a DER-encoded CMS structure containing the original profile [1]. Methods to Sign Profiles There are several standard ways to sign these files: Command Line Interface: The macOS security command is the standard built-in tool for signing profiles [7][8][3]. Command: /usr/bin/security cms -S -N "" -i <input_file>.mobileconfig -o <output_file>.mobileconfig [8][3] The -N flag specifies the certificate's common name from your login keychain [8][3]. Apple Configurator: You can use the Apple Configurator app's graphical interface to sign profiles via the File > Sign Profile menu [8][9]. MDM Tools: Many MDM platforms and associated tools (such as mdmctl) include built-in functionality to sign profiles during the upload or configuration process [7][3][10]. Certificates To sign a profile, you need a digital signing identity (certificate and private key) installed in your keychain [7][3][9]. - Trusted Certificates: For the profile to be trusted by the device without warnings, the signing certificate must be trusted by the device (e.g., issued by an internal CA trusted by your fleet or an Apple Developer ID certificate) [4][7][3]. - Restrictions: You should not use Apple Distribution certificates (intended for App Store code signing) for signing configuration profiles [11]. Key Considerations - Integrity: Signing guarantees that the profile has not been altered since it was signed [1][12]. If a device receives a signed replacement for an existing signed profile, the replacement must be signed by the same issuer, unless it is installed via the MDM protocol [1][6]. - Encryption: In addition to signing, profiles can be encrypted using CMS-enveloped data [1][6]. This is often used for security during over-the-air (OTA) delivery to protect sensitive information [6][12]. - Deployment: While signing is not strictly mandatory for all MDM deployments, it is strongly recommended for production environments to ensure integrity and improve the user experience by eliminating "unsigned" warnings [3].

Citations:

• 1: https://developer.apple.com/documentation/devicemanagement/configuring-multiple-devices-using-profiles
• 2: https://developer.apple.com/business/documentation/Configuration-Profile-Reference.pdf
• 3: https://inventivehq.com/knowledge-base/macos/how-to-create-macos-configuration-profile
• 4: https://developer.apple.com/forums/thread/699960
• 5: https://developer.apple.com/forums/thread/685723
• 6: https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/OTASecurity/OTASecurity.html
• 7: https://github.com/micromdm/micromdm/blob/main/docs/user-guide/mdmctl-signing-profiles.md
• 8: https://learn.jamf.com/r/en-US/technical-articles/Signing_a_Custom_Configuration_Profile_with_the_Installed_Certificate
• 9: https://jonbrown.org/blog/signing-mobile-config-files/
• 10: https://imazing.com/guides/how-to-sign-apple-configuration-profiles
• 11: https://forums.developer.apple.com/forums/thread/679945
• 12: https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/Introduction/Introduction.html

🌐 Web query:

Apple developer guide Configuration Profile Reference signing profiles Developer ID Installer productsign .mobileconfig

💡 Result:

Configuration profiles (.mobileconfig files) are XML property lists that can be cryptographically signed to guarantee data integrity [1][2]. Signing is recommended for production deployments to avoid "Profile is not signed" warnings and to prevent unauthorized tampering [3][4]. Signing Configuration Profiles A configuration profile is signed by wrapping the XML content in a DER-encoded, CMS (Cryptographic Message Syntax) Signed Data structure [2]. Common methods for signing profiles include: 1. GUI Tools: Applications like Apple Configurator allow you to sign a profile via the File menu (File > Sign Profile) by selecting a signing identity from your keychain [3][5]. 2. Command Line: You can use the security cms tool on macOS to sign a profile [4][5]: security cms -S -N "Common Name of Certificate" -i input.mobileconfig -o output.mobileconfig Requirement for Signing Identity: You need a valid code-signing identity (such as a Developer ID Application certificate or an internal CA certificate) installed in your login keychain [4]. While Developer ID Installer certificates are intended for Mac Installer Packages (see below), they may work for signing profiles, though a standard code-signing certificate is generally sufficient [6][4]. Clarification on Developer ID Installer and productsign It is important to distinguish between configuration profiles and Mac Installer Packages: - Configuration Profiles (.mobileconfig): These are signed using the security cms tool as described above [4][5]. - Mac Installer Packages (.pkg): These are software distribution packages that must be signed with a Developer ID Installer certificate [7][8][9]. This is performed using the productsign command-line tool or pkgbuild/productbuild [7][9]. Using a Developer ID Application certificate to sign an installer package will cause the package to fail on the destination Mac [7]. In summary, do not use productsign or Developer ID Installer certificates to sign.mobileconfig files; use the security cms utility with a standard code-signing identity. Conversely, use productsign and Developer ID Installer certificates for macOS installer packages to ensure they are accepted by Gatekeeper [7][9][10].

Citations:

• 1: https://developer.apple.com/business/documentation/Configuration-Profile-Reference.pdf
• 2: https://developer.apple.com/documentation/devicemanagement/configuring-multiple-devices-using-profiles
• 3: https://support.apple.com/guide/apple-configurator-mac/create-and-edit-configuration-profiles-pmd85719196/mac
• 4: https://inventivehq.com/knowledge-base/macos/how-to-create-macos-configuration-profile
• 5: https://learn.jamf.com/r/en-US/technical-articles/Signing_a_Custom_Configuration_Profile_with_the_Installed_Certificate
• 6: https://macblog.org/sign-configuration-profiles/
• 7: https://help.apple.com/xcode/mac/current/en.lproj/deve51ce7c3d.html
• 8: https://developer.apple.com/help/account/certificates/create-developer-id-certificates/
• 9: https://developer.apple.com/documentation/security/resolving-common-notarization-issues
• 10: https://developer.apple.com/developer-id/

🌐 Web query:

Configuration Profile Reference signing profiles Developer ID Installer productsign productsign MobileConfig Apple

💡 Result:

Apple configuration profiles (.mobileconfig files) can be signed to guarantee data integrity and prevent tampering [1][2]. Signing a profile places the XML property list into a DER-encoded, CMS (Cryptographic Message Syntax) Signed Data structure [2]. It is important to distinguish between signing configuration profiles and signing macOS installer packages: 1. Signing Configuration Profiles: You can sign profiles using various digital identities, provided they are trusted by the target device [3][4]. While a "Developer ID" certificate can be used [4][5], the primary requirement is that the signing certificate forms a chain of trust that the device recognizes [5][6]. In managed environments, this is often achieved by deploying a custom root certificate to devices, which then trusts any profiles signed by certificates issued by that root [3]. When using other certificates, you may need to include the necessary intermediate certificates in the signature so the device can verify the chain of trust [5]. Apple Configurator for Mac provides a built-in interface to sign profiles (File > Sign Profile) [7]. 2. Signing Installer Packages (productsign): The productsign command-line tool is specifically designed for signing macOS installer packages (typically.pkg files), not configuration profiles [8][9]. When signing installer packages for distribution, you must use a Developer ID Installer certificate [8][9]. Using a different certificate type, such as a Developer ID Application certificate, may result in an installer that fails to run on the destination Mac [8][9]. In summary, productsign is the standard tool for signing installer packages with a Developer ID Installer certificate [8][9], whereas configuration profiles are typically signed using tools like Apple Configurator [7] or dedicated MDM solutions [6][10] using a certificate that establishes a valid chain of trust with the target devices [3][5].

Citations:

• 1: https://developer.apple.com/business/documentation/Configuration-Profile-Reference.pdf
• 2: https://developer.apple.com/documentation/devicemanagement/configuring-multiple-devices-using-profiles
• 3: https://developer.apple.com/forums/thread/699960
• 4: https://macblog.org/sign-configuration-profiles/
• 5: https://imazing.com/guides/how-to-sign-apple-configuration-profiles
• 6: https://support.apple.com/guide/profile-manager/sign-configuration-profiles-pmd77250d7e/mac
• 7: https://support.apple.com/guide/apple-configurator-mac/create-and-edit-configuration-profiles-pmd85719196/mac
• 8: https://help.apple.com/xcode/mac/current/en.lproj/deve51ce7c3d.html
• 9: https://developer.apple.com/documentation/security/resolving-common-notarization-issues
• 10: https://jonbrown.org/blog/signing-mobile-config-files/

🌐 Web query:

site:developer.apple.com/Configuration Profile Reference signing profiles Developer ID Installer productsign Apple Configurator Profile Manager CMS

💡 Result:

Relevant Apple documentation:

• Configuration profiles and CMS signing: Apple says to sign a profile by placing its XML property list in a DER-encoded CMS Signed Data structure. Signed-profile replacements must use the same signing identity unless installed through MDM. [1]
• Developer ID signing: Developer ID certificates sign Mac apps, plug-ins, and installer packages distributed outside the Mac App Store. [2]
• Developer ID Installer: Installer packages signed with a Developer ID Installer certificate must have a currently valid certificate when run. [3]
• Provisioning profiles: Profiles contain signing certificates, device identifiers, and a bundle ID, and are used to sign and install apps. [4]
• Profile installation: MDM can install configuration profiles and provisioning profiles through dedicated commands. [5]

Sources

[1] (developer.apple.com)
[2] (developer.apple.com)
[3] (developer.apple.com)
[4] (developer.apple.com)
[5] (developer.apple.com)

Citations:

• 1: https://developer.apple.com/documentation/devicemanagement/configuring-multiple-devices-using-profiles?utm_source=openai
• 2: https://developer.apple.com/developer-id/?utm_source=openai
• 3: https://developer.apple.com/support/developer-id/?utm_source=openai
• 4: https://developer.apple.com/documentation/appstoreconnectapi/profiles?utm_source=openai
• 5: https://developer.apple.com/documentation/devicemanagement/install-profile-command?utm_source=openai

🌐 Web query:

Site:developer.apple.com Configuration Profile Reference "Developer ID Installer" "Configuration Profile"

💡 Result:

In the context of macOS software distribution, there is a distinction between a "Configuration Profile" (a system configuration file) and a "Developer ID Installer" (a signing identity) [1][2][3]. They are not the same thing, though both are involved in the deployment and management of software on macOS [1][4]. A Developer ID Installer is a specific type of digital certificate provided by Apple to developers [2][3]. It is used to sign a Mac Installer Package (PKG) for distribution outside the Mac App Store [2][4]. When a user runs an installer package signed with a Developer ID Installer certificate, Gatekeeper validates the certificate to ensure the software is from a trusted developer [3][4]. If the certificate is valid at the time the installer package is run, the installation can proceed [3]. A Configuration Profile, on the other hand, is an XML file (property list format) used to distribute configuration settings—such as Wi-Fi, VPN, or security restrictions—to macOS and iOS devices [1][5]. These profiles are often deployed via Mobile Device Management (MDM) systems or manually to configure system-level behavior across many devices [1]. While a Developer ID Installer certificate is used to sign the installer, a Configuration Profile is used to manage device settings [1][3]. They do not function as a "Developer ID Installer Configuration Profile." However, they can overlap in administrative workflows: for example, an MDM administrator might use a Configuration Profile to manage security policies (such as System Extension policies or Gatekeeper settings) that affect how an app signed with a Developer ID Installer is allowed to run on managed devices [6]. If you are encountering issues related to "Developer ID" and profiles, it is often due to one of the following: 1. Provisioning Profiles: If your application requires restricted entitlements (e.g., CloudKit, Push Notifications), you may need a Developer ID provisioning profile to authorize those claims, even for direct distribution [2][3][7]. This profile must be included within your app's bundle [7]. 2. System Policy/MDM: If you are managing devices, you might use Configuration Profiles to whitelist or approve software, system extensions, or specific Developer ID team identifiers [6]. For authoritative guidance on configuring profiles, refer to Apple's official Configuration Profile Reference [1]. For details on signing and distribution, consult the Apple Developer documentation regarding Developer ID certificates [3][4].

Citations:

• 1: https://developer.apple.com/business/documentation/Configuration-Profile-Reference.pdf
• 2: https://developer.apple.com/help/account/certificates/certificates-overview/
• 3: https://developer.apple.com/help/account/certificates/create-developer-id-certificates/
• 4: https://developer.apple.com/developer-id/
• 5: https://developer.apple.com/documentation/devicemanagement/configuring-multiple-devices-using-profiles
• 6: https://developer.apple.com/forums/thread/815340
• 7: https://developer.apple.com/documentation/xcode/creating-distribution-signed-code-for-the-mac